home *** CD-ROM | disk | FTP | other *** search
/ Merciful 1 / Merciful - Disc 1.iso / software / m / math_vision / mathvisionv2.1b.dms / mathvisionv2.1b.adf / README / dataio.doc < prev    next >
Text File  |  1992-02-14  |  9KB  |  207 lines
  1.   DataIO.Doc   How to use the DataIO hooks   12-Feb-92
  2.  
  3.   OVERVIEW
  4.  
  5.   This document describes how to access numerical data from MathVISION.
  6.   Numerical data can be encapsulated in an IFF MTRX type file.  By
  7.   keeping data in an IFF file it becomes easy to use it between
  8.   programs.  Currently only Seven Seas Software is using this format.
  9.   We will help any developers write readers and writers for this
  10.   format.  There is nothing proprietary about this format.  We will
  11.   allow you to redistribute the program that translates from ASCII
  12.   files to MTRX files.
  13.  
  14.   The MTRX file solves several data file handling problems.  The first
  15.   is saving an arbitrary data structure.  Data structures in MTRX files
  16.   are very much like structures in ` C ' and can contain arbitrary
  17.   arrangements of structures and arrays.
  18.  
  19.   Arrays not only contain sequential values, but may contain real
  20.   indexes that allows the user to interpolate between points.
  21.   Charts, for instance contain scales that represent distance and
  22.   location.  MTRX files allow scales to be attached to arrays.
  23.  
  24.   MTRX files implement matrixes as arrays of arrays.
  25.  
  26.   The basic sequence to convert a file from ASCII to MTRX and use
  27.   it with the MathVISION system is as follows:
  28.  
  29.   1. Using the program MakeMTRX, create an IFF MTRX file from your
  30.   text data file.
  31.  
  32.   2. Using the DataIO hook, load the MTRX file into memory.
  33.  
  34.   3. Write an appropriate formula in MathVISION to access the data in
  35.   memory.
  36.  
  37.   There is an intermediate format, a type of IFF file called "MTRX", 
  38.   which we have defined to store matrix data.  The program MakeMTRX 
  39.   reads your source file, and creates a MTRX file containing the same 
  40.   data, but in the MTRX structured form.  The DataIO hook reads the 
  41.   MTRX file, and stores the data in memory, so that it is quickly 
  42.   accessible to MathVISION.  In MathVISION, you must write a formula 
  43.   using one or more of the four functions `get()', `put()', `gets()', 
  44.   or `puts()' to access the data.  Here is a diagram of the data flow.
  45.  
  46. +--------+            +------+               ________   get   
  47. | Source |  MakeMTRX  | IFF  | DataIO hook  /        \  put  |==========|
  48. | Text   |===========>| MTRX |=============>| Memory |======>|| Screen ||
  49. +--------+            +------+              \________/       |==========|
  50.  
  51.  
  52.   ========================================================================
  53.   USING MakeMTRX
  54.   ========================================================================
  55.  
  56.   MakeMTRX is located in the Support directory of your MathVISION disk.  It 
  57.   is meant to be used from the CLI (Command Line Interface).  It expects 
  58.   a command line in the following format.
  59.  
  60.   MathVISION:Support/MakeMTRX Template Source Destination
  61.  
  62.   where
  63.   - Template is the name of file which describes the Source file
  64.   - Source is the name of text file which contains the data to be read
  65.   - Destination is the name of a file to be created to hold the IFF 
  66.     MTRX data.
  67.  
  68.   TEMPLATES
  69.   A Template is a file which describes the source file.  There are a number
  70.   of sample templates in the MathVISION:DataTemplates drawer.  The basic 
  71.   function of a template is to describe the structure of the data.  For
  72.   example, here is a structure definition for a 3 by 5 double-precision 
  73.   array.  For more examples, examine the templates in the DataTemplates
  74.   drawer.
  75.  
  76.   BEGINSTRUCTURE
  77.     DEFARRAY 3 0.0 1.0    ! three elements, scaled 0.0 to 1.0
  78.       DEFARRAY 5 0.0 1.0  ! five elements, scaled 0.0 to 1.0
  79.         DEFDATATYPE IEEE8 ! store double precision IEEE numbers
  80.       ENDARRAY
  81.     ENDARRAY
  82.   ENDSTRUCTURE
  83.  
  84.   This is a nested definition. You may arbitrarily create arrays of
  85.   arrays, or arrays of structures, or structures of structures, 
  86.   whatever it takes to define your data.  Arrays have elements which 
  87.   are all the same type, and they have scaling, to allow more
  88.   meaningful access using non integer indices.  Structures have fields 
  89.   which may be different types, and are always accessed with integer 
  90.   indices.
  91.  
  92.   You will probably need to edit the template and/or your data file
  93.   so they match.  First, find the template which matches your data best,
  94.   and modify it as needed to describe your data.  Hopefully you will
  95.   not have to edit your data file.  Frequently the only change you will
  96.   need to make is to modify the number of data points read.
  97.  
  98.   The reader skips over all non numeric characters that it can not
  99.   read and does a pretty good job at parsing numbers out of character
  100.   data.
  101.  
  102.   The commands which are allowed in the template for the data reader
  103.   MakeMTRX are as follows:
  104.   ----------------------------------------------
  105.  
  106.   DEFINE variablename INTEGER | REAL  ! define a new variable of given 
  107.                                         type
  108.  
  109.   ASSIGN variablename value           ! give variable a value
  110.  
  111.   DISPLAY variablename                ! print variable, good for debugging
  112.  
  113.   READ variablename [ variablename]   ! read variable value from source 
  114.                                         file
  115.  
  116.   BEGINSTRUCTURE              ! Surround the definition of whole structure
  117.   ENDSTRUCTURE
  118.  
  119.   DEFARRAY elements low_limit high_limit ! define an array
  120.     define element type here
  121.   ENDARRAY                               ! arrays have same type elements
  122.  
  123.   DEFSTRUCT fields           ! define a struct (fields of different types)
  124.   ! define field one 
  125.   ! define field two
  126.   ! define field n
  127.   ENDSTRUCT
  128.  
  129.   DEFDATATYPE FFP | IEEE8 | LONG | WORD | BYTE  ! define data in structure
  130.   ! FFP is a 4 byte real number, using the Motorola Fast Floating Point
  131.   !   encoding, and corresponds with the .ffp version of MathVISION
  132.   ! IEEE8 is an 8 byte real number, double-precision IEEE, the native
  133.   !   type of the .ieee version of MathVISION
  134.   ! LONG is a 4 byte integer
  135.   ! WORD is a 2 byte integer
  136.   ! BYTE is a 1 byte integer
  137.  
  138.   RECURSEREAD              ! fill the structure from the source file
  139.   ! How should you separate the data values?  MakeMTRX will skip all 
  140.   ! spaces, tabs, and end-of-lines, and will also skip one comma.  
  141.   ! This gives you considerable flexibility.
  142.  
  143.   LOOK at files in the MathVISION:DataTemplates drawer with an editor.
  144.  
  145.   ========================================================================
  146.   USING DataIO HOOK
  147.   ========================================================================
  148.  
  149.   The DataIO hook is in the Storage drawer of the hooks drawer.  When 
  150.   started, it creates a small window on the MathVISION edit screen.  You
  151.   have four options.
  152.  
  153.   Load IFF MTRX - load an IFF MTRX file which was created with MakeMTRX.
  154.  
  155.   Save IFF MTRX - save a file in IFF MTRX format, in case you put new 
  156.   values in it.
  157.  
  158.   Save Text - dump the values to a text file, and create another file with
  159.   ".hdr" appended which describes the format of the text file.
  160.  
  161.   Show Structure - Display the format of the currently loaded data,
  162.   including the sizes of the structures and arrays, and the scaling
  163.   applied to arrays.  This information can be copied into XMin, XMax, and
  164.   etc. for scaled access.
  165.  
  166.  
  167.   There are five functions defined for use in your formulas.  There are 
  168.   two for access using integer indices (get & put), two for access using
  169.   real coordinates (gets & puts), and finally an indication of errors
  170.   encountered when performing the getting and putting (geterr).  
  171.  
  172.   get( indices )
  173.   put( value, indices )
  174.  
  175.   There may be any number of indices, depending on the complexity of your
  176.   structure.  All indices are zero-based.  For a one-dimensional array, 
  177.   there will be one index.  For a one-dimensional array of structures, 
  178.   there will be two indices, one for the element of the array, and a
  179.   second for the field of the structure.
  180.  
  181.   gets( indices )
  182.   puts( value, indices )
  183.  
  184.   These functions work the same as get and put, except the indices which
  185.   correspond to arrays will be scaled using the array limits.  The read
  186.   in this hook does not interpolate.  It recovers the closest point to
  187.   the index.  It would be possible to build considerably more elegant
  188.   readers.
  189.  
  190.   geterr()
  191.  
  192.   If an error occured in any of the above routines, a zero is returned,
  193.   and geterr() may be used to diagnose the problem.
  194.  
  195.    The values returned are:
  196.       0  - everything OK!
  197.       1  - index out of range, either less than 0 or greater than the 
  198.               number of fields/elements.
  199.       2  - unknown structure type (internal problem)
  200.       3  - not enough indices (structure more complex than you thought!)
  201.       4  - conversion overflow - a number could not be converted to the
  202.               desired type.  Either use the IEEE version of MathVISION, or
  203.               make sure the MTRX file uses a datatype which is big enough.
  204.       5  - bad command (internal problem)
  205.       6  - too many indices (structure not as complex as you thought!)
  206.  
  207.